<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <meta charset="UTF-8"/>
  <meta name="viewport" content="width=device-width, initial-scale=1"/>
  <title>bdep-new(1) bdep 0.17.0</title>

  <style type="text/css">
/* file      : common.css
 * license   : MIT; see accompanying LICENSE file
 */

html
{
  font-family: "Helvetica Neue", Helvetica, "Segoe UI", Arial, freesans, sans-serif;
  font-weight: normal;
  font-size: 18px;
  line-height: 1.4em;
  letter-spacing: 0.01em;

  color: #292929;
}

body {margin: 0;} /* There is non-0 default margin for body. */

/* See notes on what's going on here. */
body {min-width: 17em;}
@media only screen and (min-width: 360px)
{
  body {min-width: 19em;}
}

/*
 * Header (optional).
 */

#header-bar
{
  width: 100%;

  background: rgba(0, 0, 0, 0.04);
  border-bottom: 1px solid rgba(0, 0, 0, 0.2);

  padding: .4em 0 .42em 0;
  margin: 0 0 1.4em 0;
}

#header
{
  /* Same as in #content. */
  max-width: 41em;
  margin: 0 auto 0 auto;
  padding: 0 .4em 0 .4em;

  -webkit-box-sizing: border-box;
  -moz-box-sizing: border-box;
  box-sizing: border-box;

  width: 100%;
  display: table;
  border: none;
  border-collapse: collapse;
}

#header-logo, #header-menu
{
  display: table-cell;
  border: none;
  padding: 0;
  vertical-align: middle;
}

#header-logo {text-align: left;}
#header-menu {text-align: right;}

/* These overlap with #header's margin because of border collapsing. */
#header-logo {padding-left: .4em;}
#header-menu {padding-right: .4em;}

#header-logo a
{
  color: #000;
  text-decoration: none;
  outline: none;
}
#header-logo a:visited {color: #000;}
#header-logo a:hover, #header-logo a:active {color: #000;}

#header-menu a
{
  font-size: 0.889em;
  line-height: 1.4em;
  text-align: right;
  margin-left: 1.2em;
  white-space: nowrap;
  letter-spacing: 0;
}

#header-menu a
{
  color: #000;
  outline: none;
}
#header-menu a:visited {color: #000;}
#header-menu a:hover, #header-menu a:active
{
  color: #3870c0;
  text-decoration: none;
}

/* Flexbox-based improvements though the above works reasonably well. */
#header-menu-body
{
  width: 100%;

  display: -webkit-inline-flex;
  display: inline-flex;

  -webkit-flex-flow: row wrap;
  flex-flow: row wrap;

  -webkit-justify-content: flex-end;
  justify-content: flex-end;
}

/* Whether we want it (and at which point) depends on the size of the menu. */
/*
@media only screen and (max-width: 567px)
{
  #header-menu-body
  {
    -webkit-flex-direction: column;
    flex-direction: column;
  }
}
*/

/*
 * Content.
 */

#content
{
  max-width: 41em;
  margin: 0 auto 0 auto;
  padding: 0 .4em 0 .4em; /* Space between text and browser frame. */

  -webkit-box-sizing: border-box;
  -moz-box-sizing: border-box;
  box-sizing: border-box;
}

/*
 * Footer (optional).
 */

#footer
{
  color: #767676;
  font-size: 0.7223em;
  line-height: 1.3em;
  margin: 2.2em 0 1em 0;
  text-align: center;
}

#footer a
{
  color: #767676;
  text-decoration: underline;
}
#footer a:visited {color: #767676;}
#footer a:hover, #footer a:active {color: #3870c0;}

/* Screen size indicator in the footer. The before/after content is in case
   we don't have any content in the footer. Margin is to actually see the
   border separate from the browser frame. */

/*
#footer:before {content: "\A0";}
#footer:after {content: "\A0";}

#footer
{
  border-left: 1px solid;
  border-right: 1px solid;
  margin-left: 1px;
  margin-right: 1px;
}

@media only screen and (max-width: 359px)
{
  #footer {border-color: red;}
}

@media only screen and (min-width: 360px) and (max-width: 567px)
{
  #footer {border-color: orange;}
}

@media only screen and (min-width: 568px) and (max-width: 1023px)
{
  #footer {border-color: blue;}
}

@media only screen and (min-width: 1024px)
{
  #footer {border-color: green;}
}
*/

/*
 * Common elements.
 */

p, li, dd {text-align: justify;}
.code {text-align: left;} /* Manually aligned. */
pre {text-align: left;}   /* If it is inside li/dd. */

/* Notes. */

.note
{
  color: #606060;
}

div.note
{
  margin: 2em 0 2em 0; /* The same top/bottom margings as pre box. */

  padding-left: 0.5em;
  border: 0.25em;
  border-left-style: solid;
  border-color: #808080;

  page-break-inside: avoid;
}

div.note :first-child {margin-top:    0;}
div.note :last-child  {margin-bottom: 0;}

span.note::before {content: "[Note: "}
span.note::after  {content: "]"}

/* Links. */
a
{
  color: #3870c0;
  /*color: #4078c0;*/
  text-decoration: none;
}

a:hover, a:active
{
/*color: #006fbf;*/
/*color: #0087e7;*/
  text-decoration: underline;
}

a:visited
{
/*color: #003388;*/
  color: #00409c;
}

/* Standard paragraph. */

p, pre {margin: 1em 0 1em 0;}

/* Standard lists. */
ul, ol, dl {margin: 1em 0 1em 0;}
ul li, ol li {margin: 0 0 .4em 0;}
ul li {list-style-type: circle;}
dl dt {margin: 0 0 0 0;}
dl dd {margin: 0 0 .6em 1.8em;}

code, pre
{
  font-family: Consolas, "Liberation Mono", Menlo, Courier, monospace;
  font-size: 0.92em;
  letter-spacing: 0;
}

pre {white-space: pre-wrap;}
@media only screen and (max-width: 567px)
{
  pre {word-break: break-all;}
}

/* Use page rather than system font settings. */
input
{
  font-family: inherit;
  font-weight: inherit;
  font-size:   inherit;
  line-height: inherit;
}

/* file      : pre-box.css
 * license   : MIT; see accompanying LICENSE file
 */

/* Note: see also p-code-box.css. */

pre
{
  background-color: rgba(0, 0, 0, 0.05);
  border-radius: 0.2em;
  padding: .8em .4em .8em .4em;
  margin: 2em -.4em 2em -.4em; /* Use margins of #content. */
}

/* file      : man.css
 * license   : MIT; see accompanying LICENSE file
 */

/* Bases:
 *
 * common.css
 * pre-box.css
 *
 */

#content
{
  max-width: 42.1em;
  padding-left: 1.5em; /* Reserve for the heading. */
}

h1
{
  font-weight: normal;
  font-size: 1.58em;
  line-height: 1.4em;
  margin: 1.6em 0 .6em -.88em;
}

/* Definition list for options. */
dl.options dt {margin: 1em 0 0 0;}
dl.options dd {margin: .1em 0 0 4.5em;}

/* Make lists inside option descriptions a tad smaller. */
dl.options dd ul, dl.options dd ol, dl.options dd dl
{
  font-size: 0.889em;
  line-height: 1.4em;
}

  </style>

</head>
<body>
<div id="content">

  <h1>NAME</h1>

  <p><b><code>bdep-new</code></b> &#8211; create and initialize new project</p>
  <h1>SYNOPSIS</h1>

  <p class="code"><code><b>bdep new</b> [<i>options</i>] [<b>--no-init</b>]
  <i>spec</i> [<i>name</i>]
  <br/>
  <b>bdep new</b> [<i>options</i>] <b>--config-add|-A</b> <i>cfg-dir</i>
  [<b>@</b><i>cfg-name</i>] <i>spec</i> [<i>name</i>]
  <br/>
  <b>bdep new</b> [<i>options</i>] <b>--config-create|-C</b> <i>cfg-dir</i>
  [<b>@</b><i>cfg-name</i>] <i>spec</i> [<i>name</i>]
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;[<i>cfg-args</i>]
  <br/>
  <b>bdep new</b> [<i>options</i>] <b>--package</b> [<i>prj-spec</i>]
  <i>spec</i> [<i>name</i>]
  <br/>
  <b>bdep new</b> [<i>options</i>] <b>--source</b> [<i>prj-spec</i>]
  <i>spec</i> [<i>name</i>]</code></p>

  <p class="code"><code><i>spec</i> &#160;&#160;&#160;&#160;= [<i>lang</i>]
  [<i>type</i>] [<i>vcs</i>]
  <br/>
  <i>lang</i> &#160;&#160;&#160;&#160;= <b>--lang</b>|<b>-l</b>
  (<b>c</b>|<b>c++</b>)[<b>,</b><i>lang-opt</i>...]
  <br/>
  <i>type</i> &#160;&#160;&#160;&#160;= <b>--type</b>|<b>-t</b>
  (<b>exe</b>|<b>lib</b>|<b>bare</b>|<b>empty</b>)[<b>,</b><i>type-opt</i>...]
  <br/>
  <i>vcs</i> &#160;&#160;&#160;&#160;&#160;= <b>--vcs</b>|<b>-s</b>
  &#160;(<b>git</b>|<b>none</b>)[<b>,</b><i>vcs-opt</i>...]
  <br/>
  <i>prj-spec</i> = <b>--directory</b>|<b>-d</b> <i>prj-dir</i>
  <br/>
  <i>cfg-args</i> = [<b>--</b> [<i>bpkg-options</i>]]
  [<b>--existing</b>|<b>-e</b> | (<i>module</i> |
  <i>cfg-var</i>)...]</code></p>

  <h1>DESCRIPTION</h1>

  <p>The <code><b>new</b></code> command creates and initializes a new project
  (the first three forms), a new package in an already existing project (the
  <code><b>--package</b></code> form), or a new source subdirectory in an
  already existing project/package (the <code><b>--source</b></code> form).
  All the forms except <code><b>--source</b></code> first create according to
  <code><i>spec</i></code> a new <code><b>build2</b></code> project/package
  called <code><i>name</i></code> in the <code><i>name</i></code> subdirectory
  of the current working directory (unless overridden with
  <code><b>--output-dir</b>|<b>-o</b></code> or, in case of
  <code><b>--package</b></code>, with
  <code><b>--directory</b>|<b>-d</b></code>). If <code><i>name</i></code>
  contains a directory component, then the project/package is created in this
  directory, as if it was specified with
  <code><b>--output-dir</b>|<b>-o</b></code>.</p>

  <p>The first form then, unless the <code><b>--no-init</b></code> option is
  specified, initializes an empty project database as if by executing the <a
  href="bdep-init.xhtml"><code><b>bdep-init(1)</b></code></a> command with the
  <code><b>--empty</b></code> option. For example:</p>

  <pre>$ bdep new -l c++ -t exe hello

$ tree hello/
hello/
├── hello/
│   ├── hello.cxx
│   └── buildfile
├── buildfile
└── manifest</pre>

  <p>Similarly, the second and third forms add an existing or create a new
  build configuration and then initialize the project in that configuration as
  if by executing the <a
  href="bdep-init.xhtml"><code><b>bdep-init(1)</b></code></a> command with the
  <code><b>--config-add</b></code> or <code><b>--config-create</b></code>
  option, respectively. For example:</p>

  <pre>$ bdep new -l c++ -t exe -C @gcc hello cc config.cxx=g++</pre>

  <p>The <code><b>--package</b></code> form adds the new package to the
  <code><b>packages.manifest</b></code> file creating it if necessary. If no
  project directory is explicitly specified with
  <code><b>--directory</b>|<b>-d</b></code>, then it will be deduced from the
  current working directory (see <a
  href="bdep-projects-configs.xhtml"><code><b>bdep-projects-configs(1)</b></code></a>
  for details on specifying projects). Note that nested packages are not
  allowed. For example:</p>

  <pre>$ bdep new -t empty hello
$ cd hello

$ bdep new --package -l c++ -t lib libhello
$ bdep new --package -l c++ -t exe hello

$ bdep init -C @gcc cc config.cxx=g++

$ cd ..
$ tree hello/
hello/
├── hello/
│   ├── hello/
│   │   ├── hello.cxx
│   │   └── buildfile
│   ├── buildfile
│   └── manifest
├── libhello/
│   ├── libhello/
│   │   ├── hello.hxx
│   │   ├── hello.cxx
│   │   └── buildfile
│   ├── buildfile
│   └── manifest
└── packages.manifest</pre>

  <p>The <code><b>--source</b></code> form operates <i>as-if</i> by first
  creating according to <code><i>spec</i></code> a temporary project called
  <code><i>name</i></code> and then copying its source subdirectory
  (<code><i>name</i><b>/</b><i>name</i><b>/</b></code> by default) over to the
  current working directory (unless overridden with
  <code><b>--output-dir</b>|<b>-o</b></code>). If no project/package directory
  is explicitly specified with <code><b>--directory</b>|<b>-d</b></code>, then
  the current working directory is assumed. For example:</p>

  <pre>$ bdep new -l c++ -t bare hello
$ cd hello

$ bdep new --source -l c++ -t lib libhello
$ bdep new --source -l c++ -t exe hello

$ bdep init -C @gcc cc config.cxx=g++

$ cd ..
$ tree hello/
hello/
├── hello/
│   ├── hello.cxx
│   └── buildfile
├── libhello/
│   ├── hello.hxx
│   ├── hello.cxx
│   └── buildfile
├── buildfile
└── manifest</pre>

  <p>In all the forms, if <code><i>name</i></code> is omitted, then the
  current working directory name (unless overridden with
  <code><b>--output-dir</b>|<b>-o</b></code>) is used as the
  project/package/source subdirectory name. See <a
  href="../../bpkg/doc/build2-package-manager-manual.xhtml#package-name">Package
  Name</a> for details on project/package names.</p>

  <p>The source subdirectory can be customized with the
  <code><b>subdir</b></code> project type sub-option (see below for details).
  For example:</p>

  <pre>$ bdep new -l c++ -t lib,subdir=libhello/io libhello-io

$ tree libhello-io/
libhello-io/
└── libhello/
    └── io/
        ├── hello-io.hxx
        └── hello-io.cxx</pre>

  <p>By default the source subdirectory is created in the project/package root
  directory and contains both headers (including public headers for libraries)
  as well as sources. This can be customized in a number of ways using the
  <code><b>prefix*</b></code> and <code><b>split</b></code> project type
  sub-options (see below for details). For example, to move the source
  subdirectory inside <code><b>src/</b></code>:</p>

  <pre>$ bdep new -l c++ -t exe,prefix=src hello

$ tree hello/
hello/
└── src/
    └── hello/
        └── hello.cxx</pre>

  <p>And to split the library source subdirectory into public headers and
  other source files:</p>

  <pre>$ bdep new -l c++ -t lib,split libhello

$ tree libhello/
libhello/
├── include/
│   └── libhello/
│       └── hello.hxx
└── src/
    └── libhello/
        └── hello.cxx</pre>

  <p>See the SOURCE LAYOUT section below for details and more examples.</p>

  <p>The output directory may already contain existing files provided they
  don't clash with the files to be created. The <code><b>new</b></code>
  command also recognizes certain well-known files and tries to use the
  extracted information in the package <code><b>manifest</b></code> file.
  Specifically, it tries to guess the license from the
  <code><b>LICENSE</b></code> file as well as extract the summary from
  <code><b>README.md</b></code>. This allows for the following workflow:</p>

  <pre># Create a project with LICENSE and README.md on one of the Git
# hosting services (GitHub, GitLab, etc).

$ git clone .../libhello.git
$ cd libhello

$ bdep new -l c++ -t lib</pre>

  <p>The project parameters such as language, type (executable, library, etc),
  and version control system can be customized as described next. Some of
  these parameters also support parameter-specific sub-options (such as the
  file extensions to use in a C++ project) that can be specified with a comma
  after the parameter value.</p>

  <p>The project language can be specified with the
  <code><b>--lang</b>|<b>-l</b></code> option. Valid values for this option
  and their semantics are described next. If unspecified, a C++ project is
  created by default.</p>

  <dl>
  <dt><code><b>c</b></code></dt>
  <dd>A C project. Recognized language sub-options:</dd>

  <dt style="margin-top:1em">&#160;&#160;&#160;<code><b>c++</b></code></dt>
  <dd>A C project that can also use C++. If specified, then the
  <code><b>hxx</b></code>, <code><b>cxx</b></code>, <code><b>ixx</b></code>,
  <code><b>txx</b></code>, and <code><b>mxx</b></code> <code><b>c++</b></code>
  language sub-options can also be specified.</dd>
  </dl>

  <dl>
  <dt><code><b>c++</b></code></dt>
  <dd>A C++ project. Recognized language sub-options:</dd>

  <dt style="margin-top:1em">&#160;&#160;&#160;<code><b>cpp</b></code></dt>
  <dd>Use the <code><b>.cpp</b></code>, <code><b>.hpp</b></code>,
  <code><b>.ipp</b></code>, <code><b>.tpp</b></code>, and
  <code><b>.mpp</b></code> source file extensions (alias for
  <code><b>extension=?pp</b></code>).</dd>

  <dt
  style="margin-top:1em">&#160;&#160;&#160;<code><b>extension=</b><i>pattern</i></code></dt>
  <dd>Derive source file extensions from <code><i>pattern</i></code> by
  replacing every <code><b>?</b></code> with one of the <code><b>c</b></code>
  (source), <code><b>h</b></code> (header), <code><b>i</b></code> (inline),
  <code><b>t</b></code> (template), or <code><b>m</b></code> (module
  interface) letters. If unspecified and no individual extensions are
  specified with the below options, then <code><b>?xx</b></code> is used by
  default.</dd>

  <dt
  style="margin-top:1em">&#160;&#160;&#160;<code><b>hxx=</b><i>extension</i></code></dt>
  <dd>Use the specified <code><i>extension</i></code> for header files instead
  of the default <code><b>.hxx</b></code>.</dd>

  <dt
  style="margin-top:1em">&#160;&#160;&#160;<code><b>cxx=</b><i>extension</i></code></dt>
  <dd>Use the specified <code><i>extension</i></code> for source files instead
  of the default <code><b>.cxx</b></code>.</dd>

  <dt
  style="margin-top:1em">&#160;&#160;&#160;<code><b>ixx=</b><i>extension</i></code></dt>
  <dd>Use the specified <code><i>extension</i></code> for inline files. If
  unspecified, then assume no inline files are used by the project.</dd>

  <dt
  style="margin-top:1em">&#160;&#160;&#160;<code><b>txx=</b><i>extension</i></code></dt>
  <dd>Use the specified <code><i>extension</i></code> for template files. If
  unspecified, then assume no template files are used by the project.</dd>

  <dt
  style="margin-top:1em">&#160;&#160;&#160;<code><b>mxx=</b><i>extension</i></code></dt>
  <dd>Use the specified <code><i>extension</i></code> for module interface
  files. If unspecified, then assume no modules are used by the project.</dd>

  <dt style="margin-top:1em">&#160;&#160;&#160;<code><b>c</b></code></dt>
  <dd>A C++ project that can also use C.</dd>
  </dl>

  <p>As an example, the following command creates a header-only C++ library
  that uses the <code><b>.h</b></code> extension for header files and
  <code><b>.cpp</b></code> &#8211; for source files:</p>

  <pre>$ bdep new -l c++,hxx=h,cxx=cpp -t lib,binless libhello</pre>

  <p>The project type can be specified with the
  <code><b>--type</b>|<b>-t</b></code> option. The <code><b>empty</b></code>
  project type is language-agnostic with the semantics and valid sub-options
  for the rest being language-dependent, as described next. If unspecified, an
  executable project is created by default.</p>

  <dl>
  <dt><code><b>exe</b></code></dt>
  <dd>A project that builds a sample C or C++ executable. Recognized
  executable project sub-options:</dd>

  <dt
  style="margin-top:1em">&#160;&#160;&#160;<code><b>no-tests</b></code></dt>
  <dd>Don't add support for functional/integration testing.</dd>

  <dt
  style="margin-top:1em">&#160;&#160;&#160;<code><b>unit-tests</b></code></dt>
  <dd>Add support for unit testing.</dd>

  <dt
  style="margin-top:1em">&#160;&#160;&#160;<code><b>no-install</b></code></dt>
  <dd>Don't add support for installing.</dd>

  <dt
  style="margin-top:1em">&#160;&#160;&#160;<code><b>export-stub</b></code></dt>
  <dd>Add support for importing this project's targets from other
  projects.</dd>

  <dt
  style="margin-top:1em">&#160;&#160;&#160;<code><b>prefix=</b><i>dir</i></code></dt>
  <dd>Optional source prefix relative to project/package root.</dd>

  <dt
  style="margin-top:1em">&#160;&#160;&#160;<code><b>subdir=</b><i>dir</i></code></dt>
  <dd>Alternative source subdirectory relative to source prefix.</dd>

  <dt
  style="margin-top:1em">&#160;&#160;&#160;<code><b>no-subdir</b></code></dt>
  <dd>Omit the source subdirectory.</dd>

  <dt
  style="margin-top:1em">&#160;&#160;&#160;<code><b>buildfile-in-prefix</b></code></dt>
  <dd>Create the <code><b>buildfile</b></code> in the source prefix directory
  rather than in its source subdirectory.</dd>

  <dt
  style="margin-top:1em">&#160;&#160;&#160;<code><b>third-party</b></code></dt>
  <dd>Create a package for converting an existing third-party executable to
  <code><b>build2</b></code>. This sub-option automatically enables the
  <code><b>no-readme</b></code> sub-option. It also adds a number of values to
  <code><b>manifest</b></code> that makes sense to specify in a package of a
  third-party project and, unless <code><b>no-package-readme</b></code> is
  specified, generates the <code><b>PACKAGE-README.md</b></code> template (see
  <a
  href="../../bpkg/doc/build2-package-manager-manual.xhtml#manifest-package-description"><code><b>package-description</b></code></a>
  package manifest value for background).</dd>

  <dt
  style="margin-top:1em">&#160;&#160;&#160;<code><b>license=</b><i>name</i></code></dt>
  <dd></dd>

  <dt>&#160;&#160;&#160;<code><b>no-readme</b></code></dt>
  <dd></dd>

  <dt>&#160;&#160;&#160;<code><b>no-package-readme</b></code></dt>
  <dd></dd>

  <dt>&#160;&#160;&#160;<code><b>alt-naming</b></code></dt>
  <dd>See <code><b>common</b></code> sub-options below.</dd>
  </dl>

  <dl>
  <dt><code><b>lib</b></code></dt>
  <dd>A project that builds a sample C or C++ library. Recognized library
  project sub-options:</dd>

  <dt
  style="margin-top:1em">&#160;&#160;&#160;<code><b>binless</b></code></dt>
  <dd>Create a header-only library.</dd>

  <dt
  style="margin-top:1em">&#160;&#160;&#160;<code><b>no-tests</b></code></dt>
  <dd>Don't add support for functional/integration testing.</dd>

  <dt
  style="margin-top:1em">&#160;&#160;&#160;<code><b>unit-tests</b></code></dt>
  <dd>Add support for unit testing.</dd>

  <dt
  style="margin-top:1em">&#160;&#160;&#160;<code><b>no-install</b></code></dt>
  <dd>Don't add support for installing.</dd>

  <dt
  style="margin-top:1em">&#160;&#160;&#160;<code><b>no-version</b></code></dt>
  <dd>Don't add support for generating the version header.</dd>

  <dt
  style="margin-top:1em">&#160;&#160;&#160;<code><b>no-symexport</b></code></dt>
  <dd>Don't add support for DLL symbol exporting.</dd>

  <dt
  style="margin-top:1em">&#160;&#160;&#160;<code><b>auto-symexport</b></code></dt>
  <dd>Add support for automatic DLL symbol exporting.</dd>

  <dt
  style="margin-top:1em">&#160;&#160;&#160;<code><b>prefix-include=</b><i>dir</i></code></dt>
  <dd>Optional public header prefix relative to project/package root.</dd>

  <dt
  style="margin-top:1em">&#160;&#160;&#160;<code><b>prefix-source=</b><i>dir</i></code></dt>
  <dd>Optional source prefix relative to project/package root.</dd>

  <dt
  style="margin-top:1em">&#160;&#160;&#160;<code><b>prefix=</b><i>dir</i></code></dt>
  <dd>Shortcut for
  <code><b>prefix-include=</b><i>dir</i><b>,prefix-source=</b><i>dir</i></code>.</dd>

  <dt style="margin-top:1em">&#160;&#160;&#160;<code><b>split</b></code></dt>
  <dd>Shortcut for
  <code><b>prefix-include=include,prefix-source=src</b></code>.</dd>

  <dt
  style="margin-top:1em">&#160;&#160;&#160;<code><b>subdir=</b><i>dir</i></code></dt>
  <dd>Alternative source subdirectory relative to header/source prefix.</dd>

  <dt
  style="margin-top:1em">&#160;&#160;&#160;<code><b>no-subdir-include</b></code></dt>
  <dd>Omit the source subdirectory relative to the header prefix.</dd>

  <dt
  style="margin-top:1em">&#160;&#160;&#160;<code><b>no-subdir-source</b></code></dt>
  <dd>Omit the source subdirectory relative to the source prefix.</dd>

  <dt
  style="margin-top:1em">&#160;&#160;&#160;<code><b>no-subdir</b></code></dt>
  <dd>Shortcut for
  <code><b>no-subdir-include,no-subdir-source</b></code>.</dd>

  <dt
  style="margin-top:1em">&#160;&#160;&#160;<code><b>buildfile-in-prefix</b></code></dt>
  <dd>Create the <code><b>buildfiles</b></code> in the header/source prefix
  directories rather than in their source subdirectories.</dd>

  <dt
  style="margin-top:1em">&#160;&#160;&#160;<code><b>third-party</b></code></dt>
  <dd>Create a package for converting an existing third-party library to
  <code><b>build2</b></code>. This sub-option automatically enables the
  <code><b>no-version</b></code> and <code><b>no-readme</b></code> sub-options
  as well as <code><b>no-symexport</b></code> unless
  <code><b>auto-symexport</b></code> is specified. It also adds a number of
  values to <code><b>manifest</b></code> that makes sense to specify in a
  package of a third-party project and, unless
  <code><b>no-package-readme</b></code> is specified, generates the
  <code><b>PACKAGE-README.md</b></code> template (see <a
  href="../../bpkg/doc/build2-package-manager-manual.xhtml#manifest-package-description"><code><b>package-description</b></code></a>
  package manifest value for background).</dd>

  <dt
  style="margin-top:1em">&#160;&#160;&#160;<code><b>license=</b><i>name</i></code></dt>
  <dd></dd>

  <dt>&#160;&#160;&#160;<code><b>no-readme</b></code></dt>
  <dd></dd>

  <dt>&#160;&#160;&#160;<code><b>no-package-readme</b></code></dt>
  <dd></dd>

  <dt>&#160;&#160;&#160;<code><b>alt-naming</b></code></dt>
  <dd>See <code><b>common</b></code> sub-options below.</dd>
  </dl>

  <dl>
  <dt><code><b>bare</b></code></dt>
  <dd>A project without any source code that can be filled later (see
  <code><b>--source</b></code>). Recognized bare project sub-options:</dd>

  <dt
  style="margin-top:1em">&#160;&#160;&#160;<code><b>no-tests</b></code></dt>
  <dd>Don't add support for testing.</dd>

  <dt
  style="margin-top:1em">&#160;&#160;&#160;<code><b>no-install</b></code></dt>
  <dd>Don't add support for installing.</dd>

  <dt
  style="margin-top:1em">&#160;&#160;&#160;<code><b>license=</b><i>name</i></code></dt>
  <dd></dd>

  <dt>&#160;&#160;&#160;<code><b>no-readme</b></code></dt>
  <dd></dd>

  <dt>&#160;&#160;&#160;<code><b>alt-naming</b></code></dt>
  <dd>See <code><b>common</b></code> sub-options below.</dd>
  </dl>

  <dl>
  <dt><code><b>empty</b></code></dt>
  <dd>An empty project that can be filled with packages (see
  <code><b>--package</b></code>). Recognized empty project sub-options:</dd>

  <dt
  style="margin-top:1em">&#160;&#160;&#160;<code><b>third-party</b></code></dt>
  <dd>Create a project for converting an existing third-party project to
  <code><b>build2</b></code>. This sub-option adjusts the generated
  <code><b>README.md</b></code> template wording to reflect such a
  conversion.</dd>

  <dt
  style="margin-top:1em">&#160;&#160;&#160;<code><b>no-readme</b></code></dt>
  <dd>See <code><b>common</b></code> sub-options below.</dd>
  </dl>

  <dl>
  <dt><code><b>common</b></code></dt>
  <dd>Common project type sub-options:</dd>

  <dt
  style="margin-top:1em">&#160;&#160;&#160;<code><b>license=</b><i>name</i></code></dt>
  <dd>Specify the project's license. The license name can be an <a
  href="https://spdx.org/licenses/">SPDX License Expression</a>, which, in its
  simplest form, is just the license ID. Or it can be a free form name in the
  <code><b>other:</b></code> license name scheme. If unspecified, then
  <code><b>other: proprietary</b></code> is assumed. The following tables
  lists the most commonly used free/open source software license IDs as well
  as a number of pre-defined <code><b>other:</b></code> names. See the <a
  href="../../bpkg/doc/build2-package-manager-manual.xhtml#manifest-package-license"><code><b>license</b></code></a>
  package manifest value for more information.

  <pre>MIT                MIT License.

BSD-2-Clause       BSD 2-Clause "Simplified" License
BSD-3-Clause       BSD 3-Clause "New" or "Revised" License

GPL-3.0-only       GNU General Public License v3.0 only
GPL-3.0-or-later   GNU General Public License v3.0 or later

LGPL-3.0-only      GNU Lesser General Public License v3.0 only
LGPL-3.0-or-later  GNU Lesser General Public License v3.0 or later

AGPL-3.0-only      GNU Affero General Public License v3.0 only
AGPL-3.0-or-later  GNU Affero General Public License v3.0 or later

Apache-2.0         Apache License 2.0

MPL-2.0            Mozilla Public License 2.0

BSL-1.0            Boost Software License 1.0

Unlicense          The Unlicense (public domain)</pre>

  <pre>other: public domain     Released into the public domain
other: available source  Not free/open source with public source code
other: proprietary       Not free/open source
other: TODO              License is not yet decided</pre></dd>

  <dt
  style="margin-top:1em">&#160;&#160;&#160;<code><b>no-readme</b></code></dt>
  <dd>Don't add new <code><b>README.md</b></code> (but still check for the
  existing one).</dd>

  <dt
  style="margin-top:1em">&#160;&#160;&#160;<code><b>no-package-readme</b></code></dt>
  <dd>Don't add new <code><b>PACKAGE-README.md</b></code> (but still check for
  the existing one).</dd>

  <dt
  style="margin-top:1em">&#160;&#160;&#160;<code><b>alt-naming</b></code></dt>
  <dd>Use the alternative build file/directory naming scheme.</dd>
  </dl>

  <p>The project version control system can be specified with the
  <code><b>--vcs</b>|<b>-s</b></code> option. Valid values for this option and
  their semantics are described next. If unspecified, <code><b>git</b></code>
  is assumed by default.</p>

  <dl>
  <dt><code><b>git</b></code></dt>
  <dd>Initialize a <code><b>git(1)</b></code> repository inside the project
  and generate <code><b>.gitignore</b></code> files. Recognized version
  control system sub-options:</dd>

  <dt
  style="margin-top:1em">&#160;&#160;&#160;<code><b>branch=</b><i>name</i></code></dt>
  <dd>Use the specified name for the initial branch in the newly created
  repository.</dd>
  </dl>

  <dl>
  <dt><code><b>none</b></code></dt>
  <dd>Don't initialize a version control system inside the project.</dd>
  </dl>

  <p>The created project, package, or source subdirectory can be further
  customized using the pre and post-creation hooks specified with the
  <code><b>--pre-hook</b></code> and <code><b>--post-hook</b></code> options,
  respectively. The pre hooks are executed before any new files are created
  and the post hook &#8211; after all the files have been created. The hook
  commands are executed in the project, package, or source directory as their
  current working directory. For example:</p>

  <pre>$ bdep new --post-hook "echo .idea/ >>.gitignore" hello</pre>

  <p>The pre hooks are primarily useful for moving/renaming existing files
  that would otherwise clash with files created by the <code><b>new</b></code>
  command. For example:</p>

  <pre>$ bdep new --pre-hook  "mv .gitignore .gitignore.bak" \
           --post-hook "cat .gitignore.bak >>.gitignore" \
           --post-hook "rm .gitignore.bak" ...</pre>

  <p>See the <code><b>--pre-hook</b></code> and
  <code><b>--post-hook</b></code> options documentation below for details.</p>

  <h1>NEW OPTIONS</h1>

  <dl class="options">
    <dt><code><b>--no-init</b></code></dt>
    <dd>Don't initialize an empty build configuration set.</dd>

    <dt><code><b>--package</b></code></dt>
    <dd>Create a new package inside an already existing project rather than a
    new project.</dd>

    <dt><code><b>--source</b></code></dt>
    <dd>Create a new source subdirectory inside an already existing project or
    package rather than a new project.</dd>

    <dt><code><b>--output-dir</b></code>|<code><b>-o</b></code> <code><i>dir</i></code></dt>
    <dd>Create the project, package, or source subdirectory in the specified
    directory.</dd>

    <dt><code><b>--directory</b></code>|<code><b>-d</b></code> <code><i>dir</i></code></dt>
    <dd>Assume the project/package is in the specified directory rather than
    in the current working directory. Only used with
    <code><b>--package</b></code> or <code><b>--source</b></code>.</dd>

    <dt><code><b>--type</b></code>|<code><b>-t</b></code> <code><i>type</i></code>[,<code><i>opt</i></code>...]</dt>
    <dd>Specify project type and options. Valid values for
    <code><i>type</i></code> are <code><b>exe</b></code> (executable project,
    default), <code><b>lib</b></code> (library project),
    <code><b>bare</b></code> (bare project without any source code), and
    <code><b>empty</b></code> (empty project ready to be filled with
    packages). Valid values for <code><i>opt</i></code> are
    type-specific.</dd>

    <dt><code><b>--lang</b></code>|<code><b>-l</b></code> <code><i>lang</i></code>[,<code><i>opt</i></code>...]</dt>
    <dd>Specify project language and options. Valid values for
    <code><i>lang</i></code> are <code><b>c</b></code> and
    <code><b>c++</b></code> (default). Valid values for
    <code><i>opt</i></code> are language-specific.</dd>

    <dt><code><b>--vcs</b></code>|<code><b>-s</b></code> <code><i>vcs</i></code>[,<code><i>opt</i></code>...]</dt>
    <dd>Specify project version control system and options. Valid values for
    <code><i>vcs</i></code> are <code><b>git</b></code> (default) and
    <code><b>none</b></code>. Valid values for <code><i>opt</i></code> are
    system-specific.</dd>

    <dt><code><b>--pre-hook</b></code> <code><i>command</i></code></dt>
    <dd></dd>

    <dt><code><b>--post-hook</b></code> <code><i>command</i></code></dt>
    <dd>Run the specified command before/after creating the project, package,
    or source directory.

    <p>The <code><i>command</i></code> value is interpreted as a
    whitespace-separated, potentially quoted command line consisting of a
    program or a portable <a
    href="../../build2/doc/build2-testscript-manual.xhtml#builtins">builtin</a>
    optionally followed by arguments and redirects. Specifically, a single
    level of quotes (either single or double) is removed and whitespaces are
    not treated as separators inside such quoted fragments. Currently only the
    <code><b>stdout</b></code> redirect to a file is supported. For
    example:</p>

    <pre>$ bdep new --post-hook "echo '.idea/ # IDE' >>.gitignore" hello</pre>

    <p>The command line elements (program, arguments, etc) may optionally
    contain substitutions &#8211; variable names enclosed with the
    <code><b>@</b></code> substitution symbol &#8211; which are replaced with
    the corresponding variable values to produce the actual command. The
    following variable names are recognized with the double substitution
    symbol (<code><b>@@</b></code>) serving as an escape sequence.</p>

    <pre>@mode@ - one of 'project', 'package', or 'source'
@name@ - project, package, or source subdirectory name
@base@ - name base (name without extension)
@stem@ - name stem (name base without 'lib' prefix)
@root@ - project/package root directory
@pfx@  - combined prefix relative to project/package root
@inc@  - split header prefix relative to project/package root
@src@  - split source prefix relative to project/package root
@sub@  - source subdirectory relative to header/source prefix
@type@ - type (--type|-t value: 'exe', 'lib', etc)
@lang@ - language (--lang|-l value: 'c', 'c++', etc)
@vcs@  - version control system (--vcs|-s value: 'git', etc)</pre>

    <p>Note that the <code><b>@inc@</b></code> and <code><b>@src@</b></code>
    variables are only set if the header/source prefix is split with the
    combined <code><b>@pfx@</b></code> variable set otherwise.</p>

    <p>For example:</p>

    <pre>$ bdep new --post-hook "echo bin/ >>@name@/.gitignore" hello</pre>

    <p>These substitution variables are also made available to the hook
    program as the <code><b>BDEP_NEW_*</b></code> environment variables
    (<code><b>BDEP_NEW_MODE</b></code>, <code><b>BDEP_NEW_NAME</b></code>,
    etc).</p></dd>

    <dt><code><b>--no-amalgamation</b></code></dt>
    <dd>Create a project with disabled amalgamation support. This option is
    normally only used for testing.</dd>

    <dt><code><b>--no-checks</b></code></dt>
    <dd>Suppress nested project/package checks. This option is normally only
    used for testing.</dd>

    <dt><code><b>--config-add</b></code>|<code><b>-A</b></code> <code><i>dir</i></code></dt>
    <dd>Add an existing build configuration <code><i>dir</i></code>.</dd>

    <dt><code><b>--config-create</b></code>|<code><b>-C</b></code> <code><i>dir</i></code></dt>
    <dd>Create a new build configuration in <code><i>dir</i></code>.</dd>

    <dt><code><b>--type</b></code>|<code><b>--config-type</b></code> <code><i>typ</i></code></dt>
    <dd>The type of the configuration being created. By default, configuration
    of type <code><b>target</b></code> is created. See <a
    href="../../bpkg/doc/bpkg-cfg-create.xhtml"><code><b>bpkg-cfg-create(1)</b></code></a>
    for background on configuration types.</dd>

    <dt><code><b>--default</b></code></dt>
    <dd>Make the added or created configuration the default.</dd>

    <dt><code><b>--no-default</b></code></dt>
    <dd>Don't make the first added or created configuration the default.</dd>

    <dt><code><b>--forward</b></code></dt>
    <dd>Make the added or created configuration forwarded.</dd>

    <dt><code><b>--no-forward</b></code></dt>
    <dd>Don't make the added or created configuration forwarded.</dd>

    <dt><code><b>--auto-sync</b></code></dt>
    <dd>Make the added or created configuration automatically
    synchronized.</dd>

    <dt><code><b>--no-auto-sync</b></code></dt>
    <dd>Don't make the added or created configuration automatically
    synchronized.</dd>

    <dt><code><b>--existing</b></code>|<code><b>-e</b></code></dt>
    <dd>Initialize a <code><b>bpkg</b></code> configuration based on an
    existing build system configuration.</dd>

    <dt><code><b>--wipe</b></code></dt>
    <dd>Wipe the configuration directory clean before creating the new
    configuration.</dd>

    <dt><code><b>--config-name</b></code>|<code><b>-n</b></code> <code><i>name</i></code></dt>
    <dd>Specify the build configuration as a name.</dd>

    <dt><code><b>--config-id</b></code> <code><i>num</i></code></dt>
    <dd>Specify the build configuration as an id.</dd>
  </dl>

  <h1>COMMON OPTIONS</h1>

  <p>The common options are summarized below with a more detailed description
  available in <a
  href="bdep-common-options.xhtml"><code><b>bdep-common-options(1)</b></code></a>.</p>

  <dl class="options">
    <dt><code><b>-v</b></code></dt>
    <dd>Print essential underlying commands being executed.</dd>

    <dt><code><b>-V</b></code></dt>
    <dd>Print all underlying commands being executed.</dd>

    <dt><code><b>--quiet</b></code>|<code><b>-q</b></code></dt>
    <dd>Run quietly, only printing error messages.</dd>

    <dt><code><b>--verbose</b></code> <code><i>level</i></code></dt>
    <dd>Set the diagnostics verbosity to <code><i>level</i></code> between 0
    and 6.</dd>

    <dt><code><b>--stdout-format</b></code> <code><i>format</i></code></dt>
    <dd>Representation format to use for printing to
    <code><b>stdout</b></code>.</dd>

    <dt><code><b>--jobs</b></code>|<code><b>-j</b></code> <code><i>num</i></code></dt>
    <dd>Number of jobs to perform in parallel.</dd>

    <dt><code><b>--progress</b></code></dt>
    <dd>Display progress indicators for long-lasting operations, such as
    network transfers, building, etc.</dd>

    <dt><code><b>--no-progress</b></code></dt>
    <dd>Suppress progress indicators for long-lasting operations, such as
    network transfers, building, etc.</dd>

    <dt><code><b>--diag-color</b></code></dt>
    <dd>Use color in diagnostics.</dd>

    <dt><code><b>--no-diag-color</b></code></dt>
    <dd>Don't use color in diagnostics.</dd>

    <dt><code><b>--bpkg</b></code> <code><i>path</i></code></dt>
    <dd>The package manager program to be used for build configuration
    management.</dd>

    <dt><code><b>--bpkg-option</b></code> <code><i>opt</i></code></dt>
    <dd>Additional option to be passed to the package manager program.</dd>

    <dt><code><b>--build</b></code> <code><i>path</i></code></dt>
    <dd>The build program to be used to build packages.</dd>

    <dt><code><b>--build-option</b></code> <code><i>opt</i></code></dt>
    <dd>Additional option to be passed to the build program.</dd>

    <dt><code><b>--curl</b></code> <code><i>path</i></code></dt>
    <dd>The curl program to be used for network operations.</dd>

    <dt><code><b>--curl-option</b></code> <code><i>opt</i></code></dt>
    <dd>Additional option to be passed to the curl program.</dd>

    <dt><code><b>--pager</b></code> <code><i>path</i></code></dt>
    <dd>The pager program to be used to show long text.</dd>

    <dt><code><b>--pager-option</b></code> <code><i>opt</i></code></dt>
    <dd>Additional option to be passed to the pager program.</dd>

    <dt><code><b>--options-file</b></code> <code><i>file</i></code></dt>
    <dd>Read additional options from <code><i>file</i></code>.</dd>

    <dt><code><b>--default-options</b></code> <code><i>dir</i></code></dt>
    <dd>The directory to load additional default options files from.</dd>

    <dt><code><b>--no-default-options</b></code></dt>
    <dd>Don't load default options files.</dd>
  </dl>

  <h1 id="src-layout">SOURCE LAYOUT</h1>

  <p>C and C++ projects employ a bewildering variety of source code layouts
  most of which fit into two broad classes: <i>combined</i>, where all the
  source code for a single executable or library resides in the same directory
  and <i>split</i>, where headers (typically public headers of a library) and
  other source files reside in separate directories (most commonly called
  <code><b>include/</b></code> and <code><b>src/</b></code>).</p>

  <p>To support the creation of such varying layouts the
  <code><b>new</b></code> command divides paths leading to source code inside
  a package/project into a number of customizable components:</p>

  <pre>libhello/{include,src}/hello/
    ^         ^          ^
    |         |          |
 project/   source    source
 package    prefix  subdirectory
  root</pre>

  <p>Note that while the same physical layout can be achieved with various
  combinations of source prefix and subdirectory, there will be differences in
  semantics since the headers in the project are included with the source
  subdirectory (if any) as a prefix. See <a
  href="../../build2-toolchain/doc/build2-toolchain-intro.xhtml#proj-struct">Canonical
  Project Structure</a> for rationale and details.</p>

  <p>As we have already seen, the source subdirectory can be customized with
  the <code><b>subdir</b></code> project type sub-option. For example:</p>

  <pre># libhello/hello/

$ bdep new -l c++ -t lib,subdir=hello libhello

$ tree libhello/
libhello/
└── hello/
    ├── hello.hxx
    └── hello.cxx</pre>

  <p>Note: pass <code><b>-l&#160;c++,cpp</b></code> if you prefer the
  <code><b>.hpp</b></code>/<code><b>.cpp</b></code> source file naming
  scheme.</p>

  <p>The source prefix can be combined, in which case it can be customized
  with the single <code><b>prefix</b></code> project type sub-option. For
  example:</p>

  <pre># hello/src/hello/

$ bdep new -l c++ -t exe,prefix=src hello

$ tree hello/
hello/
└── src/
    └── hello/
        └── hello.cxx</pre>

  <p>The prefix can also be split, in which case the
  <code><b>prefix-include</b></code> and <code><b>prefix-source</b></code>
  sub-options can be used to customize the respective directories
  independently. If either is omitted, then the corresponding prefix is left
  empty. For example:</p>

  <pre># libhello/{include,.}/libhello/

$ bdep new -l c++ -t lib,prefix-include=include libhello

$ tree libhello/
libhello/
├── include/
│   └── libhello/
│       └── hello.hxx
└── libhello/
    └── hello.cxx</pre>

  <p>The <code><b>split</b></code> sub-option is a convenient shortcut for the
  most common case where the header prefix is <code><b>include/</b></code> and
  source prefix is <code><b>src/</b></code>. For example:</p>

  <pre># libhello/{include,src}/libhello/

$ bdep new -l c++ -t lib,split libhello

$ tree libhello/
libhello/
├── include/
│   └── libhello/
│       └── hello.hxx
└── src/
    └── libhello/
        └── hello.cxx</pre>

  <p>The source subdirectory can be omitted by specifying the
  <code><b>no-subdir</b></code> project type sub-option. For example:</p>

  <pre># hello/src/

$ bdep new -l c++ -t exe,prefix=src,no-subdir hello

$ tree hello/
hello/
└── src/
    └── hello.cxx</pre>

  <p>The same but for the split layout (we also have to disable the generated
  version header that is not supported in this layout):</p>

  <pre># libhello/{include,src}/

$ bdep new -l c++ -t lib,split,no-subdir,no-version libhello

$ tree libhello/
libhello/
├── include/
│   └── hello.hxx
└── src/
    └── hello.cxx</pre>

  <p>To achieve the layout where all the source code resides in the project
  root, we omit both the source prefix and subdirectory (we also have to
  disable a couple of other features that are not supported in this
  layout):</p>

  <pre># hello/

$ bdep new -l c++ -t lib,no-subdir,no-version,no-tests libhello

$ tree libhello/
libhello/
├── hello.cxx
└── hello.hxx</pre>

  <p>We can also omit the source subdirectory but only in the source prefix of
  the split layout by specifying the <code><b>no-subdir-source</b></code>
  sub-option. For example:</p>

  <pre># libhello/{include/hello,src}/

$ bdep new -l c++ -t lib,split,subdir=hello,no-subdir-source libhello

$ tree libhello/
libhello/
├── include/
│   └── hello/
│       └── hello.hxx
└── src/
    └── hello.cxx</pre>

  <p>Similarly, we can also omit the source subdirectory but only in the
  header prefix of the split layout by specifying the
  <code><b>no-subdir-include</b></code> sub-option (we also have to disable
  the generated version header that is not supported in this layout):</p>

  <pre># libhello/{include,src/hello}/

$ bdep new                                                         \
  -l c++                                                           \
  -t lib,split,subdir=hello,no-subdir-include,no-version           \
  libhello

$ tree libhello/
libhello/
├── include/
│   └── hello.hxx
└── src/
    └── hello/
        └── hello.cxx</pre>

  <p>To achieve the split layout where the <code><b>include/</b></code>
  directory is inside <code><b>src/</b></code>:</p>

  <pre># libhello/src/{include,.}/hello/

$ bdep new                                                         \
  -l c++                                                           \
  -t lib,prefix-include=src/include,prefix-source=src,subdir=hello \
  libhello

$ tree libhello/
libhello/
└── src/
    ├── include/
    │   └── hello/
    │       └── hello.hxx
    └── hello/
        └── hello.cxx</pre>

  <p>A similar layout but without the source subdirectory in
  <code><b>src/</b></code>:</p>

  <pre># libhello/src/{include/hello,.}/

$ bdep new                                                         \
  -l c++                                                           \
  -t lib,prefix-include=src/include,prefix-source=src,\
subdir=hello,no-subdir-source                                      \
  libhello

$ tree libhello/
libhello/
└── src/
    ├── include/
    │   └── hello/
    │       └── hello.hxx
    └── hello.cxx</pre>

  <p>The layout used by the Boost libraries:</p>

  <pre># libhello/{include/hello,libs/hello/src}/

$ bdep new                                                         \
  -l c++                                                           \
  -t lib,prefix-include=include,prefix-source=libs/hello/src,\
subdir=hello,no-subdir-source                                      \
  libhello

$ tree libhello/
libhello/
├── include/
│   └── hello/
│       └── hello.hxx
└── libs/
    └── hello/
        └── src/
            └── hello.cxx</pre>

  <p>A layout where multiple components each have their own
  <code><b>include/src</b></code> split:</p>

  <pre># hello/libhello1/{include/hello1,src}/
# hello/libhello2/{include/hello2,src}/

$ bdep new -l c++ -t bare hello

$ bdep new -d hello --source                                       \
  -l c++                                                           \
  -t lib,\
prefix-include=libhello1/include,prefix-source=libhello1/src,\
subdir=hello1,no-subdir-source                                     \
  libhello1

$ bdep new -d hello --source                                       \
  -l c++                                                           \
  -t lib,\
prefix-include=libhello2/include,prefix-source=libhello2/src,\
subdir=hello2,no-subdir-source                                     \
  libhello2

$ tree hello/
hello/
├── libhello1/
│   ├── include/
│   │   └── hello1/
│   │       └── hello1.hxx
│   └── src/
│       └── hello1.cxx
└── libhello2/
    ├── include/
    │   └── hello2/
    │       └── hello2.hxx
    └── src/
        └── hello2.cxx</pre>

  <p>A layout where libraries and executables have different prefixes:</p>

  <pre># hello/libs/libhello/{include/hello,src}/
# hello/src/hello/

$ bdep new -l c++ -t bare hello

$ bdep new -d hello --source                                       \
  -l c++                                                           \
  -t lib,\
prefix-include=libs/libhello/include,prefix-source=libs/libhello/src,\
subdir=hello,no-subdir-source                                      \
  libhello

$ bdep new -d hello --source -l c++ -t exe,prefix=src hello

$ tree hello/
hello/
├── libs/
│   └── libhello/
│       ├── include/
│       │   └── hello/
│       │       └── hello.hxx
│       └── src/
│           └── hello.cxx
└── src/
    └── hello/
        └── hello.cxx</pre>

  <p>When packaging a third-party project for <code><b>build2</b></code>, one
  of the common approaches is to create a project with the split layout and
  the <code><b>buildfiles</b></code> in the source prefix directories rather
  than in the source subdirectories:</p>

  <pre># hello/libhello/{include,src}/hello/
# hello/libhello/{include,src}/buildfile

$ bdep new -l c -t empty hello

$ bdep new -d hello --package                                      \
  -l c                                                             \
  -t lib,                                                          \
split,subdir=hello,no-version,no-symexport,buildfile-in-prefix     \
  libhello

$ tree hello/
hello/
└── libhello/
    ├── include/
    │   ├── buildfile
    │   └── hello/
    │       └── hello.h
    └── src/
        ├── buildfile
        └── hello/
            └── hello.c</pre>

  <p>After that the upstream project is added as a <code><b>git</b></code>
  submodule to the project root directory and the source subdirectories are
  replaced with the symbolic links to the directories inside the upstream
  project directory:</p>

  <pre>$ tree hello/
hello/
├── libhello/
│   ├── include/
│   │   ├── buildfile
│   │   └── hello/ -> ../../upstream/include/hello/
│   └── src/
│       ├── buildfile
│       └── hello/ -> ../../upstream/src/
└── upstream/
    ├── include/
    │   └── hello/
    │       └── hello.h
    └── src/
        └── hello.c</pre>

  <h1>DEFAULT OPTIONS FILES</h1>

  <p>See <a
  href="bdep-default-options-files.xhtml"><code><b>bdep-default-options-files(1)</b></code></a>
  for an overview of the default options files. For the
  <code><b>new</b></code> command the search start directory is the project
  directory in the package and source modes and the parent directory of the
  new project in all other modes. The following options files are searched for
  in each directory and, if found, loaded in the order listed:</p>

  <pre>bdep.options
bdep-{config config-add}.options                # if --config-add|-A
bdep-{config config-add config-create}.options  # if --config-create|-C
bdep-new.options
bdep-new-{project|package|source}.options # (mode-dependent)</pre>

  <p>The following <code><b>new</b></code> command options cannot be specified
  in the default options files:</p>

  <pre>--output-dir|-o
--directory|-d
--package
--source
--no-checks
--config-add|-A
--config-create|-C
--wipe</pre>

  <p>While the presence of the <code><b>--pre-hook</b></code> or
  <code><b>--post-hook</b></code> options in remote default options files will
  trigger a prompt.</p>

  <h1>ENVIRONMENT</h1>

  <p>The <code><b>BDEP_AUTHOR_EMAIL</b></code> environment variable can be
  used to specify the package email address. If not set, the
  <code><b>new</b></code> command will first try to obtain the email from the
  version control system (if used) and then from the <code><b>EMAIL</b></code>
  environment variable. If all these methods fail, a dummy
  <code><b>you@example.org</b></code> email is used.</p>

  <h1>BUGS</h1>

  <p>Send bug reports to the
  <a href="mailto:users@build2.org">users@build2.org</a> mailing list.</p>

</div>

<div id="footer">
Copyright &#169; 2014-2024 the build2 authors.<br/>
Permission is granted to copy, distribute and/or modify this document under
the terms of the MIT License.
</div>

</body>
</html>
